Wireless M-Bus

This category contains functions specific to Wireless M-Bus devices.

api.wmbusSetup(operation, ...)

Overview

Changes the configuration of wM-Bus.

Operations

• power (integer) - Set wM-Bus power
• "ROLE" - Set wM-Bus role
• "MODE" - Set wM-Bus mode
• "IGNORE_CRC" - Set CRC ignore
• "DISABLE_MADDALENA_ARROW_SUPPORT" - Disable Maddalena Arrow support
• "FREQ_OFFSET" - Set frequency offset
• "RX_DUTY_CYCLE" - Set RX duty cycle
• "SONTEX_CONFIG" - Set SONTEX configuration
• "SONTEX_TUNE" - Sontex frequency offset scan

Arguments

api.wmbusSetup(power, role, mode)

• power (integer) - wM-Bus power: -20, -10, 0, 2, 4, ... [dBm]
• role (string) - wM-Bus role: "master", "slave", "meter", "concentrator", "repeater"
• mode (string) - wM-Bus mode: "S1", "S2", "T1", "T2", "T1_C", "T2_C", "R", "METRA", "SENSUS434", "SONTEX433", "BUP433", "BUP868"

api.wmbusSetup("ROLE", role)

• operation (string)
• role (string) - wM-Bus role: "master", "slave", "meter", "concentrator", "repeater"

api.wmbusSetup("MODE", mode)

• operation (string)
• mode (string) - wM-Bus mode: "S1", "S2", "T1", "T2", "T1_C", "T2_C", "R", "METRA", "SENSUS434", "SONTEX433", "BUP433", "BUP868"

api.wmbusSetup("IGNORE_CRC", ignore)

• operation (string)
• ignore (integer) - 1 for true, 0 for false

api.wmbusSetup("DISABLE_MADDALENA_ARROW_SUPPORT", disable)

• operation (string)
• disable (integer) - 1 for true, 0 for false

api.wmbusSetup("FREQ_OFFSET", offset)

• operation (string)
• offset (integer) - Set frequency offset in range from -99999 to 99999 Hz

api.wmbusSetup("RX_DUTY_CYCLE", dutyCycle, rxTime, sleepTime)

• operation (string)
• dutyCycle (integer) - Property value, or duty cycle state (true, false)
• rxTime (integer) - Duty cycle RX time
• sleepTime (integer) - Duty cycle Sleep time

api.wmbusSetup("SONTEX_CONFIG", pingRetry, readRetry, prePing, preRead, dither, demodulation)

• operation (string)
• pingRetry (integer) - Set ping retry value, range from 0 to 20
• readRetry (integer) - Set read retry value, range from 0 to 20
• prePing (integer) - Set preamble ping value, range from 0 to 10000
• preRead (integer) - Set preamble read value, range from 0 to 10000
• dither (integer) - Set dither on entry value, range from 0 to 2000
• demodulation (integer) - Set demodulation method, 1 for new method (oversampling, experimental), 0 for old method

api.wmbusSetup("SONTEX_TUNE", address, onlyRough)

• operation (string)
• address (integer) - Set address of the device to tune
• onlyRough (integer, optional) - Set only rough tuning, 1 for true, 0 for false

Return

api.wmbusSetup(power, role, mode)

• status (integer) - 0 for success, -1 for failure

api.wmbusSetup("ROLE", role)

• status (integer) - 0 for success, -1 for failure

api.wmbusSetup("MODE", mode)

• status (integer) - 0 for success, -1 for failure

api.wmbusSetup("IGNORE_CRC", ignore)

• status (integer) - 0 for success, -1 for failure

api.wmbusSetup("DISABLE_MADDALENA_ARROW_SUPPORT", disable)

• status (integer) - 0 for success, -1 for failure

api.wmbusSetup("FREQ_OFFSET", offset)

• offset (integer) - Set frequency offset

api.wmbusSetup("RX_DUTY_CYCLE", dutyCycle, rxTime, sleepTime)

• dutyCycle (integer) - Set duty cycle state
• rxTime (integer) - Set duty cycle RX time
• sleepTime (integer) - Set duty cycle Sleep time

api.wmbusSetup("SONTEX_CONFIG", pingRetry, readRetry, prePing, preRead, dither)

• pingRetry (integer) - Set ping retry value
• readRetry (integer) - Set read retry value
• prePing (integer) - Set preamble ping value
• preRead (integer) - Set preamble read value
• dither (integer) - Set dither on entry value

api.wmbusSetup("SONTEX_TUNE", address, onlyRough)

• status (integer) - 1 for success, 0 for failure
• bestOffset (integer) - Best frequency offset found

Examples

Example how to set wM-Bus power to 10 dBm, role master/concentrator and T2 mode:

api.wmbusSetup(10, "master", "T2")

Example how to set role:

api.wmbusSetup("ROLE", "master")

Example how to set mode:

api.wmbusSetup("MODE", "T1_C")

Example how to set CRC ignore:

api.wmbusSetup("IGNORE_CRC", true)

Example how to disable Maddalena Arrow support:

api.wmbusSetup("DISABLE_MADDALENA_ARROW_SUPPORT", true)

Example how to set frequency offset:

freq = api.wmbusSetup("FREQ_OFFSET", 1000)
print(freq)

Example how to set RX duty cycle:

dutyCycle, rxTime, sleepTime = api.wmbusSetup("RX_DUTY_CYCLE", 1, 1000, 1000)
print("Duty cycle: " .. dutyCycle .. ", RX time: " .. rxTime .. ", Sleep time: " .. sleepTime)

Example how to set Sontex configuration:

pingRetry, readRetry, prePing, preRead, dither = api.wmbusSetup("SONTEX_CONFIG", 10, 10, 2000, 2000, 1000)
print("Set arguments: " .. pingRetry .. ", " .. readRetry .. ", " .. prePing .. ", " .. preRead .. ", " .. dither)

api.wmbusSetHeader(cfield, manid, id, version, devtype, ci)

Overview

Sets wM-Bus header.

Arguments

• cfield (integer) - wM-Bus C field, max value 0xff
• manid (integer) - Manufacturer ID, max value 0xffff
• id (integer) - ID of wM-Bus device (32 bit)
• version (integer) - Version fields, max value 0xff
• devtype (integer) - Device version field, max value 0xff
• ci (integer) - CI field, max value 0xff

Return

• status (integer) - 0 for success, -1 for failure

Example

-- Set wM-Bus header for specific device 
print("--- wM-Bus T1 Digital Thermometer ---") 
api.wmbusSetup(10, "meter", "T1")
api.wmbusSetHeader(123, 123456, 2, 33, 17)

api.wmbusSendFrame(data)

Overview

Sends frame through wM-Bus.

Arguments

• data (string) - Frame to be sent

Return

• status (integer) - Positive or 0 for success, negative for failure

Example

-- Send wM-Bus frame
api.wmbusSendFrame(frame)

api.wmbusReceiveFrame(timeout, ...)

Overview

Waits for data reception from wM-Bus.

Arguments

SONTEX433 mode

api.wmbusReceiveFrame(timeout, id)

• timeout (integer) - The maximum time in milliseconds to wait for WMBUS device answer
• id (integer) - ID of wM-Bus device (32 bit)

Other modes

api.wmbusReceiveFrame(timeout, debugOn, useFilter)

• timeout (integer) - The maximum time in milliseconds to wait for WMBUS device answer
• debugOn (integer, optional) - Debug on: 1 for true, 0 for false
• useFilter (integer, optional) - Use filter: 1 for true, 0 for false

Return

METRA mode

• status (integer) - Positive or 0 for success, negative for failure
• cField (nil) - Unused field, pushed as nil
• manID (integer) - Manufacturer ID (0x0614 for Apator SA)
• devID (integer) - Unique 32-bit ID of the wM-Bus device
• ver (nil) - Unused field, pushed as nil
• devType (integer) - Device type field (max value 0xff)
• ciField (nil) - Unused field, pushed as nil
• dataOnly (string) - Data-only portion of the frame
• rawFrame (string) - Complete frame, including length and CRC
• filterIndex (integer) - Index of the filter
• rssi (integer) - Received Signal Strength Indicator
• frameType (string) - Identifier for METRA: "M"
• transportType (string) - Error/status message, default "ERR"

SONTEX433 mode

• status (integer) - Positive or 0 for success, negative for failure
• cField (nil) - Unused field, pushed as nil
• manID (integer) - Manufacturer ID (0x4DEE for Sontex SA)
• devID (integer) - Unique 32-bit ID of the wM-Bus device
• ver (nil) - Unused field, pushed as nil
• devType (nil) - Unused field, pushed as nil
• ciField (nil) - Unused field, pushed as nil
• dataOnly (string) - Data-only portion of the frame
• rawFrame (string) - Complete frame, including length and CRC
• filterIndex (nil) - Unused field, pushed as nil
• rssi (integer) - Received Signal Strength Indicator
• frameType (string) - Identifier for SONTEX433: "SONTEX433"
• transportType (string) - Error/status message, default "ERR"

BUP433 and BUP868 modes

• status (integer) - Positive or 0 for success, negative for failure
• cField (nil) - Unused field, pushed as nil
• manID (integer) - Manufacturer ID (0x4CAE for Sensus GmbH)
• devID (integer) - Unique 32-bit ID of the wM-Bus device
• ver (nil) - Unused field, pushed as nil
• devType (integer) - Device type field (max value 0xff)
• ciField (nil) - Unused field, pushed as nil
• dataOnly (string) - Data-only portion of the frame
• rawFrame (string) - Complete frame, including length and CRC
• filterIndex (integer) - Index of the filter
• rssi (integer) - Received Signal Strength Indicator
• frameType (string) - Identifier for BUP433 and BUP868: "BUP"
• transportType (string) - Error/status message, default "ERR"

Other modes

• status (integer) - Positive or 0 for success, negative for failure
• cField (integer) - Control Field from the wM-Bus frame (max value 255)
• manID (integer) - Manufacturer ID, with a maximum value of 0xffff
• devID (integer) - Unique 32-bit ID of the wM-Bus device
• ver (integer) - Version of the device (max value 0xff)
• devType (integer) - Device type field (max value 0xff)
• ciField (integer) - Control information field
• dataOnly (string) - Received frame payload
• rawFrame (string) - Complete frame without CRC
• filterIndex (integer) - Index of the filter
• rssi (integer) - Received Signal Strength Indicator
• frameType (string) - Frame type: "F", "C", "T", "S", "T2S", or "ERR"
• transportType (string) - Transport type: "A", "B", or "ERR"

Example

-- Receive wM-Bus data with 2000 ms timeout 
status, cField, manID, devID, ver, devType, ciField, dataOnly = api.wmbusReceiveFrame(2000)
print(status)
print(devID)
print(dataOnly)

api.wmbusReceiveSendFrame(ci, payload, timeout)

Overview

Waits for data reception from the wM-Bus. After reception, the received frame can be modified and sent back to the device.

warning

This function is only available when the wM-Bus is in the concentrator role.

Arguments

• ci (integer) - CI field
• payload (string) - Payload to be send
• timeout (integer) - The maximum time in milliseconds to wait for RS485 device answer
• useFilter (integer, optional) - Use filter: 1 for true, 0 for false

Return

• status (integer) - Positive or 0 for success, negative for failure
• cField (integer) - Control Field from the wM-Bus frame (max value 255)
• manID (integer) - Manufacturer ID, with a maximum value of 0xffff
• devID (integer) - Unique 32-bit ID of the wM-Bus device
• ver (integer) - Version of the device (max value 0xff)
• devType (integer) - Device type field (max value 0xff)
• ciField (integer) - Control Information field as received in the frame
• dataOnly (string) - Payload data extracted from the received frame
• rawFrame (string) - Complete received frame without CRCs
• filterIndex (integer) - Index of the filter
• rssi (integer) - Received Signal Strength Indicator
• frameType (string) - Frame type: "F", "C", "T", "S", "T2S", or "ERR"
• transportType (string) - Transport type: "A" or "B", or "ERR"

Example

x=string.char(0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF)
status, cField, manID, devID, ver, devType, ciField, dataOnly = api.wmbusReceiveFrame(2000)
print(status)
print(devID)
print(dataOnly)

api.wmbusSendReceiveFrame(ci, payload)

Overview

Sends a frame with the specified Control Information and payload from a wM-Bus device in the meter role and listens for a response.

warning

This function is only available when the wM-Bus is in the meter role.

Arguments

api.wmbusSendReceiveFrame(ci, payload, debugOn, useFilter)

• ci (integer) -CI field
• payload (string) - Payload to be send
• debugOn (integer, optional) - Debug on: 1 for true, 0 for false
• useFilter (integer, optional) - Use filter: 1 for true, 0 for false

Return

• status (integer) - Positive or 0 for success, negative for failure
• cField (integer) - wM-Bus C field (max value 255)
• manID (integer) - Manufacturer ID, max value 0xffff
• devID (integer) - ID of wM-Bus device (32 bit)
• ver (integer) - Version fields, max value 0xff
• devType (integer) - Device version field, max value 0xff
• ciField (integer) - CI field
• payload (string) - Received frame payload
• rawFrame (string) - Complete frame without CRC
• rssi (integer) - Received Signal Strength Indicator

Example

x=string.char(0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF)
status, cField, manID, devID, ver, devType, ciField, dataOnly = api.wmbusSendReceiveFrame(200, x)
print(status)
print(devID)
print(dataOnly)

api.wmbusFilter(operation, ...)

Overview

Creates and manages internal table of wM-Bus IDs.

warning

This function is only available when the wM-Bus is in the meter role.

Operations

• "purge" - Purges the table, removing all stored IDs
• "populate" - Populates the table with a set of IDs provided as input
• "show" - Shows the content of filter
• "fetch" - Returns length of filter
• "show-length" - Shows length of the filter
• "show-index" - Shows index for defined filter
• "add" - Adds ID to the filter (max length 4B)

Arguments

api.wmbusFilter("purge")

• operation (string)

api.wmbusFilter("populate", filter)

• operation (string)
• filter (string) - Filter data to populate; must be a multiple of 4 bytes in length.

api.wmbusFilter("show")

• operation (string)

api.wmbusFilter("fetch")

• operation (string)

api.wmbusFilter("show-length")

• operation (string)

api.wmbusFilter("show-index", index)

• operation (string)
• index (integer) - The index of the filter to show (1-based).

api.wmbusFilter("add", id)

• operation (string)
• id (string) - Single 4-byte filter entry to add.

Return

api.wmbusFilter("purge")

• status (integer) - Returns 0 on success

api.wmbusFilter("populate", filter)

• status (integer) - Number of filters populated on success, negative values on failure

api.wmbusFilter("show")

• status (integer) - Returns the length of the filter table on success
• entries (string) - Concatenated filter entries as a string, each 4 bytes

api.wmbusFilter("fetch")

• status (integer) - 0 if fetch was successful, negative values on failure
• length (integer) - Current length of the wM-Bus filter table

api.wmbusFilter("show-length")

• length (integer) - Length of the wM-Bus filter table

api.wmbusFilter("show-index", index)

• entry (string) - Specific filter entry at the given index; returns an empty string if the index is invalid

api.wmbusFilter("add", id)

• status (integer) - Returns the new filter length on success, negative values on failure

Examples

Example how to purge wM-Bus filter:

api.wmbusFilter("purge")

Example how to populate wM-Bus filter:

filter = ""
filter = filter .. string.char(0x13, 0x32, 0x67, 0x01) -- 0x01673213
filter = filter .. string.char(0x33, 0x47, 0x85, 0x19) -- 0x19854733
api.wmbusFilter("populate", filter)

Example how to show wM-Bus filter:

status, entries = api.wmbusFilter("show")
print(entries)

Example how to fetch wM-Bus filter:

status, length = api.wmbusFilter("fetch")
print(length)

Example how to show length of wM-Bus filter:

length = api.wmbusFilter("show-length")
print(length)

Example how to show index of wM-Bus filter:

status, entry = api.wmbusFilter("show-index", 1)
print(entry)

Example how to add wM-Bus filter:

id = string.char(0x13, 0x32, 0x67, 0x01) -- 0x01673213
api.wmbusFilter("add", id)